[AWS]API Gatewayの本文マッピングテンプレートを理解する

#Amazon API Gateway

#AWS

千葉淳

2017.09.12

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

コンニチハ、千葉です。

はじめに

API Gatewayを利用すると、RESTful APIを作成、配布、保守、監視、保護できるようになります。ユーザーがAPI Gatewayへリクエストを送信すると、バックエンド、例えばEC2やLambda、KinesisなどへリクエストのPOSTやクエリパラメータなどの情報をプロキシすることができます。

マッピングテンプレートを利用すると、バックエンドへプロキシする情報をカスタマイズすることができます。必要な情報のみ転送することで、バックエンド側の処理をシンプルにすることができます。

例えば、API Gateway > KinesisFirehose > S3 の構成でリクエストデータを保存する場合、必要な情報のみを保存することができます。

やってみた

マッピングテンプレートの設定方法

まずはマッピングテンプレートの設定方法です。統合リクエストより設定します。

20170908-api-gateway-mapping-template-1

マッピングテンプレートから設定します。

20170908-api-gateway-mapping-template-2

リクエスト本文のパススルーの設定

パススルーの設定項目で3種類選択できます。この設定項目は、

マッピングテンプレートに従った変換を行い、バックエンドにデータ転送する
リクエストのデータを、変換せずにバックエンドにパススルーする
リクエスト拒否(HTTP 415 Unsupported Media Type)

の何れかを行います。この挙動を設定します。

1.リクエストの Content-Type ヘッダーに一致するテンプレートがない場合

マッピングテンプレートを定義していない場合(空の場合) > 変換せずにパススルーする
リクエストヘッダとマッピングテンプレートのContent-Typeが一致の場合 > マッピングテンプレートに従いデータ変換する
リクエストヘッダとマッピングテンプレートのContent-Typeが不一致の場合 > 変換せずにパススルーする

2.テンプレートが定義されていない場合 (推奨)

マッピングテンプレートを定義していない場合(空の場合) > 変換せずにパススルーする
リクエストヘッダとマッピングテンプレートのContent-Typeが一致の場合 > マッピングテンプレートに従いデータ変換する
リクエストヘッダとマッピングテンプレートのContent-Typeが不一致の場合 > リクエスト拒否(HTTP 415 Unsupported Media Type)

3. なし

マッピングテンプレートを定義していない場合(空の場合) > リクエスト拒否(HTTP 415 Unsupported Media Type)
リクエストヘッダとマッピングテンプレートのContent-Typeが一致の場合 > マッピングテンプレートに従いデータ変換する
リクエストヘッダとマッピングテンプレートのContent-Typeが不一致の場合 > リクエスト拒否(HTTP 415 Unsupported Media Type)

マッピングテンプレートの追加

以下はKinesisFirehoseへデータ転送する時の例です。クエリパラメータhogeを取得し、Base64でエンコードしたあとにバックエンドへjsonを送信します。

{
  "DeliveryStreamName": "apigw-kinesis",
  "Record": {
    "Data": "$util.base64Encode($input.params('hoge'))"
  }
}

$util.base64Encod、$input.params('no')は本文マッピングテンプレートで予め用意されている組み込み関数です。

マッピングテンプレートの組み込み変数

マッピングテンプレートで用意されている組み込み関数一覧です。

API Gateway マッピングテンプレートの組み込み関数と変数

クエリパラメータ、POSTされたデータ、クライアントのソースIP等、取得してバックエンドに転送することができます。マッピングテンプレートで定義されていないデータについては、バックエンドをLambdaにして必要な情報を埋め込む必要があります。2017/9時点ではマッピングテンプレートでリクエスト受け付け時間に関するデータは取得できないので、Lambdaをバックエンドにして対応するしかないです。